---
title: 'Jira'
sidebarTitle: 'Jira'
description: 'Access the Jira API in 2 minutes 💨'
---

import { StatusWidget } from "/snippets/api-down-watch/status-widget.jsx"

<StatusWidget service="jira" />

<Tabs>
  <Tab title="🚀 Quickstart">
    <Steps>
      <Step title="Create an integration">
        In Nango ([free signup](https://app.nango.dev)), go to [Integrations](https://app.nango.dev/dev/integrations) -> _Configure New Integration_ -> _Jira_.
      </Step>
      <Step title="Authorize Jira">
        Go to [Connections](https://app.nango.dev/dev/connections) -> _Add Test Connection_ -> _Authorize_, then log in to Jira. Later, you'll let your users do the same directly from your app.
      </Step>
      <Step title="Call the Jira API">
        Let's make your first request to the Jira API (fetch a list of issues). Replace the placeholders below with your [secret key](https://app.nango.dev/dev/environment-settings), [integration ID](https://app.nango.dev/dev/integrations), and [connection ID](https://app.nango.dev/dev/connections):
        <Tabs>
            <Tab title="cURL">
                ```bash
                curl "https://api.nango.dev/proxy/ex/jira/{connectionConfig.cloudId}/rest/api/3/search?maxResults=10" \
                  -H "Authorization: Bearer <NANGO-SECRET-KEY>" \
                  -H "Provider-Config-Key: <INTEGRATION-ID>" \
                  -H "Connection-Id: <CONNECTION-ID>"
                ```
            </Tab>

            <Tab title="Node">

            Install Nango's backend SDK with `npm i @nangohq/node`. Then run:

            ```typescript
            import { Nango } from '@nangohq/node';

            const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });

            const res = await nango.get({
                endpoint: '/ex/jira/{connectionConfig.cloudId}/rest/api/3/search',
                params: {
                  maxResults: 10
                },
                providerConfigKey: '<INTEGRATION-ID>',
                connectionId: '<CONNECTION-ID>'
            });

            console.log(JSON.stringify(res.data, null, 2));
            ```
            </Tab>

        </Tabs>

        Or fetch credentials dynamically via the [Node SDK](/reference/sdks/node#get-a-connection-with-credentials) or [API](/reference/api/connection/get).

        <Note>
        The `{connectionConfig.cloudId}` in the URL represents the cloudId. You can get this value from your connection configuration after creating the connection. The cloudId is automatically set by Nango.
        </Note>

      </Step>
    </Steps>

    ✅ You're connected! Check the [Logs](https://app.nango.dev/dev/logs) tab in Nango to inspect requests.

    <Tip>
    Next step: [Embed the auth flow](/getting-started/quickstart/embed-in-your-app) in your app to let your users connect their Jira accounts.
    </Tip>
  </Tab>
  <Tab title="🧑‍💻 OAuth app setup">
    <Steps>
      <Step title="Create an Atlassian developer account">
        If you don't already have one, sign up for an [Atlassian developer account](https://id.atlassian.com/signup/).
      </Step>
      <Step title="Create a new OAuth 2.0 (3LO) app">
        1. Go to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/).
        2. Click **Create** and select **OAuth 2.0 integration**.
        3. Enter a name, agree to Atlassian's developer terms by checking the agreement checkbox for your app and click **Create**.
        4. Your app will be created and you'll be taken to the app management page.
      </Step>
      <Step title="Configure OAuth 2.0 (3LO)">
        1. In the left sidebar, select **Authorization**.
        2. Next to OAuth 2.0 (3LO), click **Add**.
        3. Enter `https://api.nango.dev/oauth/callback` as the **Callback URL**.
        4. Click **Save Changes** to save your changes.
      </Step>
      <Step title="Add API permissions">
        1. In the left sidebar, select **Permissions**.
        2. Find the Jira API and click **Add**, and then click **Configure**.
        3. Click **Edit Scopes** then select the [scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/#scopes) your application requires. For reference, see our [Common Scopes](#common-scopes) table below.
        4. Click **Save** to save your changes.
      </Step>
      <Step title="Obtain your client credentials">
        1. In the left sidebar, select **Settings**.
        2. Note your **Client ID**.
        3. Copy both the **Client ID** and **Secret** by clicking the copy buttons next to them, as you'll need them when configuring your integration in Nango.
      </Step>
      <Step title="Make your app available to users">
        1. In the left sidebar, select **Distribution**.
        2. In **Distribution controls**, click the **Edit** button, select the **Sharing** radio button, enter a **Privacy Policy URL** and then click the **Save changes** button.
       <Note>By default, your app is private and can only be used by you. Making it public allows other users to authorize your app.</Note>
      </Step>
      <Step title="Next">
        Follow the [_Quickstart_](/getting-started/quickstart).
      </Step>
    </Steps>

    ## Common Scopes

    | Scope | Description |
    | ----- | ----------- |
    | read:jira-user | Read user information |
    | read:jira-work | Read Jira work items (issues, projects, etc.) |
    | write:jira-work | Create and update Jira work items |
    | delete:jira-work |  Delete issues |
    | manage:jira-project |  Manage project settings |
    | manage:jira-configuration |  Manage Jira instance settings |
    | offline_access | Access to refresh tokens for offline access |

  </Tab>
  <Tab title="🔗 Useful links">
    | Topic | Links |
    | - | - |
    | General | [Atlassian Developer Portal](https://developer.atlassian.com/) |
    | | [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) |
    | | [Jira Cloud Platform Documentation](https://developer.atlassian.com/cloud/jira/platform/) |
    | Developer | [OAuth 2.0 (3LO) Apps Documentation](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) |
    | | [OAuth Scopes Reference](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/) |
    | | [Jira REST API v3 Documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) |
    | | [API Rate Limits](https://developer.atlassian.com/cloud/jira/platform/rate-limiting/) |
    | | [Basic Auth Documentation](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/) |
    | | [Distributing OAuth 2.0 Apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#distributing-your-oauth-2-0--3lo--apps) |
    | | [Atlassian Marketplace](https://marketplace.atlassian.com/) |

    <Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/jira.mdx)</Note>
  </Tab>
  <Tab title="🚨 API gotchas">
    - Refreshing tokens require the `offline_access` scope when creating the integration on the Nango UI.
    - When connecting to Jira, you have two options for specifying which Jira site to connect to:
      1. Provide a `Subdomain` during connection creation (recommended)
      2. Let Nango auto-select the first available site (legacy behavior): If no `Subdomain` is specified, Nango will use the first site from the accessible resources api.

    ```ts
    const response = await nango.get({
        endpoint: `oauth/token/accessible-resources`,
        baseUrlOverride: 'https://api.atlassian.com'
    });
    const cloudId = response.data[0].id;
    ```

    - A single Jira OAuth token can be valid for multiple Atlassian sites. For example, the same token might grant access to both "nango-hq.atlassian.net" and "nango-test.atlassian.net". This is why specifying the `Subdomain` during connection creation is important if you need to connect to a specific site.

    - The connection process works as follows:
      1. Nango fetches all accessible sites for the OAuth token
      2. If you specified a `Subdomain`, Nango finds the matching site and sets its `cloudId`
      3. If no `Subdomain` is specified, Nango uses the first available site and sets its `cloudId`
      4. The selected site's `cloudId` and `subdomain` are stored in the connection configuration
    - The `cloudId` is required to make API requests to the Jira API `v3`. Nango handles getting this automatically by matching it to your specified `subdomain` if provided, or by selecting the first available site if it is not. You will then need to construct your Nango integration's `endpoint` as follows: `/ex/jira/${cloudId}/rest/api/3/<endpoint>`
    - When you create an OAuth 2.0 (3LO) app, it's private by default. Before using the integration, you must make your app public. If you want to make your app public, find the how-to [here](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#distributing-your-oauth-2-0--3lo--apps).
    - Refresh tokens will expire after 365 days of non use and will expire by 90 days if the resource owner is inactive for 90 days. Make sure you call `nango.getConnection()` at least every 365 days to trigger a refresh. See reference [here](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#how-do-i-get-a-new-access-token--if-my-access-token-expires-or-is-revoked-).
    - When making API calls, remember that the permissions of the user who authorized your app will limit what your app can do, regardless of the scopes you've requested.
    - The Jira REST API has different versions (v2 and v3). Make sure you're using the correct version for your needs.

    <Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/jira.mdx)</Note>
  </Tab>
</Tabs>

<Info>
    Questions? Join us in the [Slack community](https://nango.dev/slack).
</Info>
